Summary

Refactors the /api/request route handler from a 346-line monolith into a set of focused, individually testable modules, adds a vitest-based test suite (now wired into CI), introduces lightweight server-side analytics for airdrop outcomes, and tightens a couple of security and operational rough edges surfaced while pulling things apart.

A security-equivalence audit (old monolith vs new modular implementation) is in the Security review section below — no controls weakened.

Module split — app/api/request/

route.ts is now a thin entrypoint; the logic lives in:

• handler.ts — orchestrates a request end-to-end
• validation.ts — body parsing + 400 INVALID_BODY for non-object bodies (null, arrays)
• ip.ts — client IP extraction, sanitization, and IP-allow-list parsing (fault-tolerant: invalid JSON now falls back to [] instead of breaking all traffic)
• auth-bypass.ts — auth-token bypass with timing-safe comparison (timingSafeEqual) replacing the old ==
• rate-limiting.ts — rate-limit checks
• verify-captcha.ts — Cloudflare Turnstile verification
• execute-airdrop.ts — Solana airdrop call
• airdrop-error.ts — error → HTTP status + user-facing message mapping (NO_KEYPAIR now correctly 500 instead of 400; everything else preserved)
• tracking.ts — analytics + backend transaction recording
• types.ts — shared RequestContext / AirdropResponse types; faucetKeypair and authToken are non-enumerable with a toJSON returning <redacted>, so an accidental console.log(ctx) cannot leak them

Tests — vitest

• New vitest.config.ts with __tests__-scoped include pattern: app/**/__tests__/**/*.test.ts, lib/**/__tests__/**/*.test.ts
• 100+ tests covering each module plus the route handler
• Wired into CI (.github/workflows/ci.yml) so npm test runs on every PR

Analytics — lib/analytics.ts

Server-side GA4 Measurement Protocol wrapper that records airdrop outcome events (airdrop_success, airdrop_failed with structured reason) from API routes. Fire-and-forget — never throws, never blocks the airdrop response. No PII: full wallet addresses are shortened to XXXX...YYYY before being sent; sanitized IP is used only as the GA4 client_id for visitor grouping; no auth tokens or keypair material are ever emitted. Disabled cleanly when env vars are unset.

Library cleanup

• Extract lib/utils.ts + lib/constants.ts into focused lib/airdrop/ (AIRDROP_TIERS, VALID_AMOUNTS, resolveTier) and lib/rpc.ts (getConnection, per-network env-aware) modules
• Tighten getClientIp (drop dead ?? undefined)
• Rewrite getRpcUrl tests with vi.resetModules() + dynamic import so stubbed env is picked up (RPC_URLS is captured at import time)

Backend client fixes (lib/backend.ts)

• Bypass callers (IP-allowlisted / auth-token) were silently dropped from the audit trail: backend's POST /api/transactions is .strict() with githubIdSchema.optional() (regex /^\d+$/), and passing "" failed the regex with a 400 swallowed by the surrounding logging try/catch. Pass ctx.githubUserId directly so JSON.stringify omits the key when undefined and the backend accepts it as missing.
• Rename FaucetTransaction.github_username → github_id to match the column the backend actually returns; rename the local getLastTransactions JS param accordingly. Wire format unchanged — the HTTP query key was already github_id.
• Type transactionsAPI.create's github_id as string | undefined.
• Remove dead methods: solanaBalancesAPI.getAllForAccount and githubValidationAPI target backend routes that don't exist and have no callers.

Other fixes folded into this PR

• fix: restrict IP_ALLOW_LIST to rate-limit bypass only — preserves the old monolith's semantics: an IP-allow-listed caller still gets captcha-checked and still needs GitHub auth; the allow-list only skips rate-limit lookup.
• fix: redact-secrets helper — the RequestContext mentioned above (non-enumerable secrets + toJSON: <redacted>), with a regression test that asserts JSON.stringify(ctx) does not contain the keypair or auth token.

Behavior changes worth flagging

Verified against the pre-refactor monolith on main:

1. Bypass-token callers no longer require a GitHub session. Old code enforced GITHUB_LOGIN_REQUIRED = true unconditionally, so a bypass-token caller without a GitHub login was rejected. Aligns with the whole point of bypass tokens (machine/CI use) and with the backend github_id becoming optional. IP-allow-listed callers still need GitHub in both versions.
2. Amount validation is now a strict whitelist. Old: 0 < amount ≤ maxAmountPerRequest accepted 0.1, 3, and (latent bug) negative numbers. New: only values in VALID_AMOUNTS = [0.5, 1, 2.5, 5] are accepted. UI is unaffected; any external/scripted caller posting non-whitelisted amounts will now get a 400.
3. INVALID_BODY 400 for malformed bodies (null, arrays, non-JSON), previously a generic 500.

Everything else — Cloudflare IP determination with dev ::1 fallback, captcha skip conditions (fail-closed on Cloudflare errors), rate-limit math, validationAPI / transactionsAPI argument order and wire keys, faucet signing keypair, lamports math, priority fee, record-fail-open, error message strings — is preserved bit-for-bit.

Test plan

• npm test — full vitest suite passes (100+ tests, all green)
• npx tsc --noEmit — type-clean
• Security-equivalence audit vs pre-refactor monolith
• Manual: hit /api/request with a valid wallet + Turnstile token → airdrop succeeds, transaction recorded
• Manual: hit /api/request from an IP-allow-listed caller → captcha still required, GitHub still required, but rate limit skipped
• Manual: hit /api/request with a valid bypass token → captcha/GitHub/rate-limit all skipped, transaction recorded with github_id omitted
• Manual: hit /api/request with a malformed body (null, array, non-JSON) → 400 INVALID_BODY
• Manual: hit /api/request with amount: 0.1 → 400 (was previously accepted)
• Manual: trigger rate limit → 429, analytics airdrop_failed with reason: rate_limited
• Manual: invalid Turnstile token → 400, analytics airdrop_failed with reason: captcha_failed
• Manual on preview deploy: verify RPC_URL_DEVNET is set and devnet airdrops route through the private RPC